File Download Element

The File Download Element works in conjunction with the File Upload Element, allowing users to download files within a form which have previously been uploaded using the File Upload Element. The files can have been uploaded from the same or a different form and can be stored as files or within the File Upload database. As far as the Download Element is concerned, it makes no difference whether the file is stored within the file system or the database.

The File Download Element consists of a single button which the form user can click or tap in order to download a file. The file to be downloaded will be determined by the input mappings assigned to the Element (see the Data tab properties below for more details). The file will be downloaded and can be opened and/or saved in the standard manner for the browser running the form.

You will need to be familiar with the operation of the File Upload Element, in order to use the File Download Element. In particular, you will need to know the connection string for the File Upload table's sister database table which contains the records of the uploaded files you want to access from this form. You don't need to create a Datasource and Dataset for the File Upload table, NDLFXFile, this will be done automatically by Digitise Forms when you publish your form.

You can add multiple File Download Elements to a form if you want to allow users to download more than one file per data record.

 

When you add a File Download Element to your form, you need to create a Datasource and Dataset for the relevant File Upload's sister table and allow for this Dataset to be downloaded to the form, e.g. using a Button with its Clicked Event configured to load the Datasource or using the Loads with Form property.

In addition, you will need to provide a means for a user to locate the record(s), in the sister table, containing the details about the uploaded file(s) they want to download. For example, you could add appropriate Elements to the form, input mapped to the sister table, to display information which would identify the current record to the user. Buttons could be provided to allow the user to move through the records in the sister Dataset, until they reach a record whose associated file(s) they want to download. They could then use the File Download Element to download the file. If each record contains multiple file uploads and your user may want to download more than one file from a record, you will need to add separate File Download Elements for each file to be downloaded.

 

 

The File Upload Element stores uploaded files, which are saved as files, in the form's Fileuploads folder below the form's web app root folder, e.g. C:\inetpub\wwwroot\<project name>\Fileuploads.

The user under which the IIS Application Pool running your form is running will need read permissions to the folder storing the files to be downloaded. If the Application Pool is running under the ApplicationPoolIdentity user refer to the FAQs for information on giving this user access to your specified folder.

If you have stored uploaded files in the database, on the other hand, you will need to specify a suitable user to access the databases holding the uploaded file records within the connection string(s) for the relevant Datasources.

 

By default IIS restricts file downloads to a maximum file size of 2GB.

 

Once you have placed a File Download Element on a page, you can edit the Element's properties to configure the Element for your requirements. Select the Element on the page to display its properties in the Properties Pane.

The following properties are available:

Name and Code Name

Visible and Disabled Properties

Allows you to specify the label you want to display on the face of the Button, to indicate the Button's function.

Alternatively, you can read the label text in from a Datasource. This input mapping is available here on the Appearance tab within the Text property, rather than on the Data tab. There is no output mapping available for this property.

If you specify an input mapping, the mapping will be displayed, in the Form Design workspace, in the format {<datasource>.<dataset>.<dataitem>} in place of the text and the in-line editor will be disabled, since you don't need to be able to edit the text as this will be supplied from the datasource. For example:

Picture showing Download button displaying input mapping configured to provide label text.

You may need to reload the form to display the input mapping. The mapping is only shown in the Form Studio and isn't displayed on the published form.

You could also set the value of the button's text from within custom Javascript, using the Element's text property.

For more information about specifying input and output mappings refer to the topic: Map Data to Elements.

Allows you to specify a picture to be displayed on the Button. If you specify a value in the Text property above, the position of the image in relation to the label is defined in the Image Position property on the Advanced tab, Picture showing Advanced tab..

To browse for the picture, click on Picture showing Browse button. at the right-hand end of the property. A standard file browse dialog will be displayed allowing you to locate and select the required picture. If you want to re-use a picture that you have already used in this project, click on the down arrow symbol at the end of the edit box instead. This will display a list of images used in the project and you can select the one you want.

If you want to change the picture, simply select the new picture you want to use instead or to clear the selection, click on Picture showing the Close button. to the right of the Picture showing the Browse button. button.

The properties under this tab are used to specify a record which contains the required information about the file to be downloaded.

You will need a Datasource and Dataset which maps to the File Upload table's sister table containing the records of the relevant file uploads.

You will then need to input map the ID Field and File Field properties for this Element. At runtime the value in the ID Field mapping will tell the Element which record from the sister table contains the information identifying the file you want to download and the value in the File Field column of that record will identify the file in the corresponding NDLFXFile table which stores the file name and path or file contents, depending upon whether the file was stored to the file system or the database.

The File ID property should, therefore, be input mapped to the Primary Key field of the sister table. You can specify a specific GUID by selecting Static Value, rather than Datasource, within the Mapping Builder, but this will restrict the File Download Element to only allow the downloading of the file referenced in the File Field column of the record whose Primary Key matches the GUID entered, no matter what the current record is.

The File Field property should be input mapped to the column in the sister table which holds the unique identifiers (GUIDs) assigned to the previously uploaded files, i.e. the column in the sister table to which the File Upload Element which uploaded the file was output mapped. This field in the sister Dataset will have a data type of GUID and by default will be named after the File Upload Element on the form used to upload the files.

For example, lets suppose you have a form which allows potential new members to apply for membership of a club. This form asks applicants for some details about themselves and asks them to upload two files which contain scanned images of identifying documentation, such as a driving licence. You now want to create a second form which will allow admin staff at the club to check the applications and view the uploaded identifying documentation. On this second form you will need to have two File Download Elements, one for each piece of documentation originally uploaded. You will also need to create an imported Datasource with a Dataset mapped to the File Upload table's sister table to provide access to the data stored by the application form. If you open this Dataset from the Datasources tab in the Project Explorer pane, it might look something like this:

Picture showing example File Upload Table's Sister Table Dataset open in Form Studio.

Notice the two fields with data type Guid, IDImage1 and IDImage2. These will hold the unique identifiers assigned to the images when they were uploaded and which provide the link to the file details stored in the NDLFXFile table.

The first File Download Element on your admin form, would need it's ID Field property mapped to the Primary Key field of this Dataset, in this case the OnlineApplicationID column, and its File Field property to the first file upload column, in this case IDImage1.

The second File Download Element, would need it's ID Field property mapped to the same Primary Key field as the first File Download Element, OnlineApplicationID, but its File Field property would be mapped to the second file upload column, IDImage2.

Your admin form would need to allow the user to locate the relevant application and allow them to download the associated files for that record. For example, you could add a Recordset to your admin form, configure it to use page editor mode and input map it to the sister table so that it lists all new applications which need checking. The form user could then select an application from this list and click the edit button to load the Recordset's edit page, which would include the two File Download Elements allowing them to download the files.

 

You shouldn't normally need to create a Datasource for the NDLFXFile table, in which case Digitise Forms will automatically create one when you publish your form. A warning message will be displayed informing you that the Datasource has been created and you will need to cancel the publish in order to complete the connection string for this database, under the Datasources category of the publish profile settings. The Dataset for this Datasource will be visible under the Datasources tab in the Profile Explorer, but you cannot view or edit it.

At this point, you can also change the instance of SQL Server the NDLFXFile database is stored in, if it is stored in a different SQL Server instance than its sister table, e.g. if you are using a single, centralised version of this file for all file uploads but you have stored the other form data on other SQL Server instances. Alternatively, in this situation, you can create a separate imported Datasource to import the NDLFXFile database and table yourself, but you would still map the File Download Element's Data properties to the columns mentioned earlier in the sister table.

Note that you can also import the NDLFXFile Database and then map your File Download Element(s) directly to the NDLFXFile Dataset within it, although in this case you would need to input map both properties under the Data tab, ID Field and File Field, to the NDLFXFile Dataset's FileId column. However, if you do this, your form will have access to all file uploads stored in this database, which may include files uploaded from more than one form. Mapping a File Download Element via a sister table will only show your form users file uploads recorded in the sister table imported for the form. Note also that you must not change the names of the NDLFXFile database, table or columns or the File Download Element will not work.

 

You can also use the Download Element to download files which are not recorded in the NDLFXFile database. To do this, you will need a database containing records which have a string-based column containing the full path and file names of the files you want to download, e.g. C:\MyUploads\Myfile.pdf, and a Primary Key field with a data type of GUID (uniqueidentifier). In this situation, you would create an imported Datasource to import the database and the relevant table holding the file details and then input map the File Download Element's ID Field to the Dataset's Primary Key field and the File Field to the column containing the file path and names.

This can be useful if you are upgrading from an earlier version of Digitise Forms, which didn't use the NDLFXFile table, and you had forms which included file uploads. Note, however, that you will need to edit the database table storing the records of these earlier file uploads to include the full path with the file name as earlier versions of FX only saved the file name and didn't include the file path.

 

If you move uploaded files from the original form's Fileuploads folder and you want to make them accessible to the File Downloads Element, you will need to edit the NDLFXFile table used by the File Upload Element to record the file uploads, and change the file paths for all relevant records to match the new location of the files. You could do this using Microsoft's SQL Server Management Studio.

  • Remember, publishing a form deletes the Fileuploads folder and its contents. Consequently, if you are republishing a form which contains one or more File Upload Elements which used this folder to store uploaded files, you will need to backup the folder before you publish, if you want to retain any previously uploaded files.

 

You cannot specify an output mapping for the File Download Element.

For more information about mapping properties to data items in a Datasource see Data Tab Properties.

Clicked Event

Be careful if specifying the Clicked Event that you don't include anything which is inconsistent with the behaviour of this Element and which will, therefore, cause the Event to malfunction.

Image Category

Image Position

Determines whether the image specified in the Image property above is displayed to the left or right of the Button's label. If the Text property, above, is blank, this property is ignored.

 

Image Height

Specifies the height, in pixels, for the image. If you specify the height but not the width, the width will automatically be adjusted to maintain the original aspect ratio of the image. If you leave both the height and width blank the image will be displayed at its actual size.

 

Image Width

Specifies the width, in pixels, for the image. If you specify the width but not the height, the height will automatically be adjusted to maintain the original aspect ratio of the image. If you leave both the height and width blank the image will be displayed at its actual size.

 

Styles Category

Label Style

Allows you to assign a style to the Button's Label, e.g. to set the font type, size and colour.

 

Button Style

Allows you to assign a style to the body of the Button, e.g. to set the background colour.


 

 

See also:

File Upload